feat(creator-keys): expose subscription access gating with on-chain hold check - #988

Closes #953
Closes #899
Closes #959
Closes #977

Two problems, not one

The module was never compiled in. creator-keys/src/curve_subscriptions_swaps.rs already contained subscribe_key_access, is_subscribed, KeySubscription and SUBSCRIPTION_GRANTED_EVENT, but lib.rs has no mod curve_subscriptions_swaps;. None of it existed in the built contract. Now declared.

The helper's signature can't be the contract's surface. It takes the balance and the minimum as parameters:

pub fn subscribe_key_access(
    env: &Env, creator: &Address, subscriber: &Address,
    duration_ledgers: u32,
    min_keys: u32,
    subscriber_balance: u32,   // ← supplied by the caller
) -> Result<u32, ContractError>

Exposed as-is, the minimum-hold check is self-attested — any wallet passes subscriber_balance: u32::MAX and gates itself in. Fine for an internal helper; a hole as an entry point.

The new entry points read both values from storage: balance via get_key_balance, minimum from DataKey::MinHoldForAccess. The threshold is enforced against what the ledger actually says.

Added

Decisions worth review

The creator cannot set their own threshold — admin only. This gates paid access. A creator who could lower it at will could admit wallets holding nothing, which is exactly what the gate exists to prevent. Say the word if you'd rather creators self-serve.

Automatic revocation is evaluated on read, not swept by a job. is_subscribed re-checks the live balance against the minimum recorded on the subscription, so access lapses the moment a holder sells below the threshold — no revocation transaction, and no window in which a sold-down wallet still passes.

Dropping below the minimum doesn't destroy the record, so topping back up restores access for the remainder of the term. That felt right for a paid subscription, but it is a product call — there's a test either way, so flipping it is a one-line change.

Raising the minimum doesn't retroactively revoke. The subscription stores the minimum in force when granted, so an increase applies to new subscriptions rather than voiding paid-for access mid-term.

A zero minimum is rejected — it would gate nothing while looking configured. Removing the key is the honest way to disable gating, and an unconfigured creator returns NotRegistered rather than InsufficientBalance so an operator can tell "gating is off" from "you need more keys".

get_subscription is exposed because the boolean alone can't tell a caller why access was denied — expired, or under threshold — and a UI needs to say which.

Verification

Not run. 13 tests in creator-keys/tests/subscription_access_gating.rs, written against the repo's existing contract_test_env helpers and driving everything through the contract entry points (buying and selling real keys to move balances rather than passing a balance in). They have never been compiled or executed — please treat as unverified.

The most likely thing to need a fix: my setup() helper leaks the Env via Box::leak to get a 'static client out of a tuple-returning function. It matches what the surrounding tests achieve with an inline let env = ..., but if the crate's test style objects, inlining setup per test removes the need for it.